home *** CD-ROM | disk | FTP | other *** search
/ The World of Computer Software / The World of Computer Software.iso / xmm12.zip / XMM.PAS < prev    next >
Pascal/Delphi Source File  |  1992-07-05  |  45KB  |  927 lines
  1.   {--------------------------------------------------------------------------
  2.      UNIT :          XMM                           INITIAL : 19891127 v 1.00
  3.      AUTHOR :        Jeroen W. Pluimers            UPDATE :  19920705 v 1.20
  4.  
  5.      DESCRIPTION :   eXpanded Memory Manager
  6.  
  7.      HISTORY :       19891127 - 1.00 - jwp
  8.  
  9.                          initial translation from XMS 2.0 specification
  10.  
  11.                      19909322 - 1.11 - jwp
  12.  
  13.                          final XMS 2.0 implementation
  14.  
  15.                      19920705 - 1.20 - jwp
  16.  
  17.                          incorporation of XMS 3.0 specification
  18.  
  19.      COMPUTER :      NEAT-AT, ERC 386/25
  20.      COMPILER :      TURBO PASCAL 5.0, 5.5 and 6.0
  21.  
  22.      COPYRIGHT :     (c) 1989-1992 Pluimers Software Ontwikkeling.
  23.    --------------------------------------------------------------------------}
  24.  
  25. Unit XMM;
  26.  
  27. {$I Directive.Inc }
  28.  
  29. Interface
  30.  
  31. Type
  32.   XMMMoveRec = Record Case Boolean of
  33.     False : (Length       : Longint;  { 32-bit number of bytes to transfer   }
  34.              SourceHandle : Word;     { Handle of source block               }
  35.              SourceOffset : Longint;  { 32-bit offset into source            }
  36.              DestHandle   : Word;     { Handle of destination block          }
  37.              DestOffset   : Longint;  { 32-bit offset into destination block }
  38.             );
  39.    True   : (TheLenght    : Longint;  { note that the lenght must be even !  }
  40.              ZeroSource   : Word;     { zero sourcehandle means a seg:ofs    }
  41.              SourcePtr    : Pointer;  { pointer to "normal" memory           }
  42.              ZeroDest     : Word;     { zero dest handle means a seg:ofs     }
  43.              DestPtr      : Pointer;  { pointer to "normal" memory           }
  44.             );
  45.   End; { XMMMoveRec }
  46.  
  47. Const
  48.  
  49.   XMMOk              = $00;{ function succeeded.                              }
  50.  
  51.   XMMNotImplemented  = $80;{ the function is not implemented.                 }
  52.   XMMVDiskFound      = $81;{ a VDISK device is detected.                      }
  53.   XMMA20Err          = $82;{ an A20 error occurs.                             }
  54.   XMMGenErr          = $8E;{ a general driver error occurs.                   }
  55.   XMMUnrecovErr      = $8F;{ an unrecoverable driver error occurs.            }
  56.  
  57.   XMMHMAnotExist     = $90;{ the HMA does not exist.                          }
  58.   XMMHMAInUse        = $91;{ the HMA is already in use.                       }
  59.   XMMHMAminSize      = $92;{ DX is less than the /HMAMIN= parameter.          }
  60.   XMMHMANotAlloced   = $93;{ the HMA is not allocated.                        }
  61.   XMMA20StillEnabled = $94;{ the A20 line is still enabled.                   }
  62.  
  63.   XMMOutOfMemory     = $A0;{ all extended memory is allocated.                }
  64.   XMMOutOfHandles    = $A1;{ all available extended memory handles are in use.}
  65.   XMMInvalidHandle   = $A2;{ the handle is invalid.                           }
  66.   XMMSourceHanldeInv = $A3;{ the SourceHandle is invalid.                     }
  67.   XMMSourceOffsetInv = $A4;{ the SourceOffset is invalid.                     }
  68.   XMMDestHanleInv    = $A5;{ the DestHandle is invalid.                       }
  69.   XMMDestOffset      = $A6;{ the DestOffset is invalid.                       }
  70.   XMMLenInv          = $A7;{ the Length is invalid.                           }
  71.   XMMOverlap         = $A8;{ the move has an invalid overlap.                 }
  72.   XMMParity          = $A9;{ a parity error occurs.                           }
  73.   XMMEMBUnlocked     = $AA;{ the block is not locked.                         }
  74.   XMMEMBLocked       = $AB;{ the block is locked.                             }
  75.   XMMLockOverflow    = $AC;{ the block's lock count overflows.                }
  76.   XMMLockFail        = $AD;{ the lock fails.                                  }
  77.  
  78. Function XMMInstalled : Boolean;
  79.   {---------------------------------------------------------------------------
  80.      ROUTINE :     XMMInstalled
  81.  
  82.      DESCRIPTION : THIS ROUTINE MUST BE CALLED BEFORE ANY OTHER ROUTINE
  83.                    OR ALL THE OTHER ROUTINES WILL FAIL WITH ERROR CODE $80.
  84.  
  85.      RETURNS :     False - No XMM driver found.
  86.                    True  - An XMM driver has been found.
  87.  
  88.      POST :        Internal pointer to XMM driver is established.
  89.    ---------------------------------------------------------------------------}
  90.  
  91. Function XMMVersion(Var XMSversion,
  92.                         XMSrevision  : Word;
  93.                     Var HMAAvailable : Boolean) : Byte;
  94.   {---------------------------------------------------------------------------
  95.      ROUTINE :     XMMVersion
  96.  
  97.      DESCRIPTION : Get version numbers. Both the XMS version number and the
  98.                    driver internal revision number are encoded as follows :
  99.                      Low byte  = minor part.
  100.                      High byte = major part.
  101.                    e.g. XMSversion $0277 would mean version 2.77.
  102.                    The HMAAvailable indicates the existence of the HMA (not
  103.                    its availability) and is intended mainly for installation
  104.                    programs.
  105.  
  106.      OUT :         XMSversion   - XMS version number.
  107.                    XMSrevision  - Driver internal revision number.
  108.                    HMAAvailable - False - no HMA detected.
  109.                                   True  - HMA has been detected.
  110.  
  111.      RETURNS :     XMMOk              - Always if XMMInstalled has been called.
  112.                    XMMNotImplemented  - XMMInstalled has not been called.
  113.  
  114.      PRE :         XMMInstalled must have been called first.
  115.    ---------------------------------------------------------------------------}
  116.  
  117. Function XMMRequestHMA (SpaceNeeded : Word) : Byte;
  118.   {---------------------------------------------------------------------------
  119.      ROUTINE :     XMMRequestHMA
  120.  
  121.      DESCRIPTION : Attempts to reserve the whole 64K-16 byte high memory
  122.                    area for the caller.
  123.                    If the HMA is currently unused, the caller's size
  124.                    parameter is compared to the /HMAMIN= parameter on
  125.                    the driver's command line.
  126.                    If the value passed by the caller is greater than or
  127.                    equal to the amount specified by the driver's
  128.                    parameter, the request succeeds.
  129.                    This provides the ability to ensure that programs
  130.                    which use the HMA efficiently have priority over
  131.                    those which do not.
  132.                    NOTE: See the sections "Prioritizing HMA Usage" and
  133.                          "High Memory Area Restrictions" in the
  134.                          documentation for more information.
  135.  
  136.      IN :          SpaceNeeded - Number of bytes in the HMA needed by caller.
  137.                                  It is recommended that if the caller is
  138.                                  an application program this value is
  139.                                  set to 65535 and if the caller is a TSR
  140.                                  the real number of bytes is used.
  141.  
  142.      RETURNS :     XMMOk              - the HMA is assigned to the caller.
  143.                    XMMNotImplemented  - the function is not implemented.
  144.                    XMMVDiskFound      - a VDISK device is detected.
  145.                    XMMHMANotExist     - the HMA does not exist.
  146.                    XMMHAMInUse        - the HMA is already in use.
  147.                    XMMHAMMinSize      - SpaceNeeded is less than the /HMAMIN=
  148.                                         environment parameter.
  149.  
  150.      PRE :         XMMInstalled must have been called first.
  151.    ---------------------------------------------------------------------------}
  152.  
  153. Function XMMReleaseHMA : Byte;
  154.   {---------------------------------------------------------------------------
  155.      ROUTINE :     XMMReleaseHMA
  156.  
  157.      DESCRIPTION : Releases the high memory area and allows other
  158.                    programs to use it.
  159.                    Programs which allocate the HMA must release it
  160.                    before exiting.
  161.                    When the HMA has been released, any code or data
  162.                    stored in it becomes invalid and should not be
  163.                    accessed.
  164.  
  165.      RETURNS :     XMMOk              - the HMA is successfully released.
  166.                    XMMNotImplemented  - the function is not implemented.
  167.                    XMMVDiskFound      - a VDISK device is detected.
  168.                    XMMHMANotExist     - the HMA does not exist.
  169.                    XMMNotAllocated    - the HMA was not allocated.
  170.  
  171.      PRE :         XMMInstalled must have been called first.
  172.    ---------------------------------------------------------------------------}
  173.  
  174. Function XMMGlobalEnableA20 : Byte;
  175.   {---------------------------------------------------------------------------
  176.      ROUTINE :     XMMGlobalEnableA20
  177.  
  178.      DESCRIPTION : Attempts to enable the A20 line.
  179.                    It should only be used by programs which have control
  180.                    of the HMA.
  181.                    The A20 line should be turned off via
  182.                    XMMGlobalDisableA20 before a program releases control
  183.                    of the system.
  184.                    NOTE: On many machines, toggling the A20 line is a
  185.                          relatively slow operation.
  186.  
  187.      RETURNS :     XMMOk              - the A20 line is enabled.
  188.                    XMMNotImplemented  - the function is not implemented.
  189.                    XMMVDiskFound      - a VDISK device is detected.
  190.                    XMMA20Err          - and A20 error occurs.
  191.  
  192.      PRE :         XMMInstalled must have been called first.
  193.    ---------------------------------------------------------------------------}
  194.  
  195. Function XMMGlobalDisableA20 : Byte;
  196.   {---------------------------------------------------------------------------
  197.      ROUTINE :     XMMGlobalDisableA20
  198.  
  199.      DESCRIPTION : Attempts to disable the A20 line.
  200.                    It should only be used by programs which have control
  201.                    of the HMA.
  202.                    The A20 line should be disabled before a program
  203.                    releases control of the system.
  204.                    NOTE: On many machines, toggling the A20 line is a
  205.                          relatively slow operation.
  206.  
  207.      RETURNS :     XMMOk              - the A20 line is disabled.
  208.                    XMMNotImplemented  - the function is not implemented.
  209.                    XMMVDiskFound      - a VDISK device is detected.
  210.                    XMMA20Err          - and A20 error occurs.
  211.                    XMMA20StillEnabled - the A20 line is still enabled.
  212.  
  213.      PRE :         XMMInstalled must have been called first.
  214.    ---------------------------------------------------------------------------}
  215.  
  216. Function XMMLocalEnableA20 : Byte;
  217.   {---------------------------------------------------------------------------
  218.      ROUTINE :     XMMLocalEnableA20
  219.  
  220.      DESCRIPTION : Attempts to enable the A20 line.
  221.                    It should only be used by programs which need direct
  222.                    access to extended memory.
  223.                    Programs which use this function should call
  224.                    XMMLocalDisableA20 before releasing control of the
  225.                    system.
  226.                    NOTE: On many machines, toggling the A20 line is a
  227.                          relatively slow operation.
  228.  
  229.      RETURNS :     XMMOk              - the A20 line is enabled.
  230.                    XMMNotImplemented  - the function is not implemented.
  231.                    XMMVDiskFound      - a VDISK device is detected.
  232.                    XMMA20Err          - and A20 error occurs.
  233.  
  234.      PRE :         XMMInstalled must have been called first.
  235.    ---------------------------------------------------------------------------}
  236.  
  237. Function XMMLocalDisableA20 : Byte;
  238.   {---------------------------------------------------------------------------
  239.      ROUTINE :     XMMLocalDisableA20
  240.  
  241.      DESCRIPTION : Cancels a previous call to XMMLocalEnableA20.
  242.                    It should only be used by programs which need direct
  243.                    access to extended memory.
  244.                    Previous calls to XMMLocalEnableA20 must be canceled
  245.                    before releasing control of the system.
  246.                    NOTE: On many machines, toggling the A20 line is a
  247.                          relatively slow operation.
  248.  
  249.      RETURNS :     XMMOk              - the A20 line is disabled.
  250.                    XMMNotImplemented  - the function is not implemented.
  251.                    XMMVDiskFound      - a VDISK device is detected.
  252.                    XMMA20Err          - and A20 error occurs.
  253.                    XMMA20StillEnabled - the A20 line is still enabled.
  254.  
  255.      PRE :         XMMInstalled must have been called first.
  256.    ---------------------------------------------------------------------------}
  257.  
  258. Function XMMQueryA20 (Var A20IsOn : Boolean) : Byte;
  259.   {---------------------------------------------------------------------------
  260.      ROUTINE :     XMMQueryA20
  261.  
  262.      DESCRIPTION : Checks to see if the A20 line is physically enabled.
  263.                    It does this in a hardware independent manner by
  264.                    seeing if "memory wrap" occurs.
  265.  
  266.      OUT :         A20IsOn  - False - the A20 line is not physically enabled.
  267.                               True  - the A20 line us physically enabled.
  268.  
  269.      RETURNS :     XMMOk              - the function succeeds.
  270.                    XMMNotImplemented  - the function is not implemented.
  271.                    XMMVDiskFound      - a VDISK device is detected.
  272.  
  273.      PRE :         XMMInstalled must have been called first.
  274.    ---------------------------------------------------------------------------}
  275.  
  276. Function XMMQueryFree (Var LargestFree,
  277.                            TotalFree : Word): Byte;
  278.   {---------------------------------------------------------------------------
  279.      ROUTINE :     XMMQueryFree
  280.  
  281.      DESCRIPTION : Returns the size of the largest available extended
  282.                    memory block and total free memory in the system.
  283.                    NOTE: The 64K HMA is not included in the returned
  284.                          value even if it is not in use.
  285.  
  286.      OUT :         LargestFree - Size of the largest free extended
  287.                                  memory block in K-bytes.
  288.                    TotalFree   - Total amount of free extended memory in
  289.                                  K-bytes.
  290.  
  291.      RETURNS :     XMMOk              - the function succeeds.
  292.                    XMMNotImplemented  - the function is not implemented.
  293.                    XMMVDiskFound      - a VDISK device is detected.
  294.                    XMMOutOfMemory     - all available extended memory is
  295.                                         allocated.
  296.  
  297.      PRE :         XMMInstalled must have been called first.
  298.    ---------------------------------------------------------------------------}
  299.  
  300. Function XMMAllocateEMB (    BlockSize : Word;
  301.                          Var Handle    : Word) : Byte;
  302.   {---------------------------------------------------------------------------
  303.      ROUTINE :     XMMAllocateEMB
  304.  
  305.      DESCRIPTION : Attempts to allocate a block of the given size out of
  306.                    the pool of free extended memory.
  307.                    If a block is available, it is reserved for the
  308.                    caller and a 16-bit handle to that block is returned.
  309.                    The handle should be used in all subsequent extended
  310.                    memory calls.
  311.                    If no memory was allocated, the returned handle is
  312.                    null.
  313.  
  314.                    NOTE: Extended memory handles are scarce resources.
  315.                          Programs should try to allocate as few as
  316.                          possible at any one time.
  317.                          When all of a driver's handles are in use, any
  318.                          free extended memory is unavailable.
  319.  
  320.      IN :          BlockSize - Amount of extended memory being requested
  321.                                in K-bytes.
  322.  
  323.      OUT :         Handle    - 16-bit handle to the allocated block.
  324.  
  325.      RETURNS :     XMMOk              - the block is allocated.
  326.                    XMMNotImplemented  - the function is not implemented.
  327.                    XMMVDiskFound      - a VDISK device is detected.
  328.                    XMMOutOfMemory     - all available extended memory is
  329.                                         allocated.
  330.                    XMMOutOfHandles    - all available extended memory
  331.                                         handles are in use.
  332.  
  333.      PRE :         XMMInstalled must have been called first.
  334.    ---------------------------------------------------------------------------}
  335.  
  336. Function XMMFreeEMB (Handle : Word) : Byte;
  337.   {---------------------------------------------------------------------------
  338.      ROUTINE :     XMMFreeEMB
  339.  
  340.      DESCRIPTION : This function frees a block of extended memory which
  341.                    was previously allocated using XMMAllocateEMB.
  342.                    Programs which allocate extended memory should free
  343.                    their memory blocks before exiting.
  344.                    When an extended memory buffer is freed, its handle
  345.                    and all data stored in it become invalid and should
  346.                    not be accessed.
  347.  
  348.      IN :          Handle - 16-bit handle to the allocated block which
  349.                             should be freed.
  350.  
  351.      RETURNS :     XMMOk              - the block is allocated.
  352.                    XMMNotImplemented  - the function is not implemented.
  353.                    XMMVDiskFound      - a VDISK device is detected.
  354.                    XMMInvalidHandle   - the handle is invalid.
  355.                    XMMEMBLocked       - the block is locked.
  356.  
  357.      PRE :         XMMInstalled must have been called first.
  358.    ---------------------------------------------------------------------------}
  359.  
  360. Function XMMMoveEMB (MoveRec : XMMMoveRec) : Byte;
  361.   {---------------------------------------------------------------------------
  362.      ROUTINE :     XMMMoveEMB
  363.  
  364.      DESCRIPTION : This function attempts to transfer a block of data
  365.                    from one location to another.
  366.                    It is primarily intended for moving blocks of data
  367.                    between conventional memory and extended memory,
  368.                    however it can be used for moving blocks within
  369.                    conventional memory and within extended memory.
  370.  
  371.                    NOTE: If SourceHandle is set to 0000h, the
  372.                          SourceOffset is interpreted as a standard
  373.                          segment:offset pair which refers to memory that
  374.                          is directly accessible by the processor.
  375.                          The segment:offset pair is stored in Intel
  376.                          DWORD notation.  The same is true for
  377.                          DestHandle and DestOffset.
  378.           
  379.                    SourceHandle and DestHandle do not have to refer to
  380.                    locked memory blocks.
  381.           
  382.                    Length must be even.  Although not required,
  383.                    WORD-aligned moves can be significantly faster on
  384.                    most machines. DWORD aligned move can be even faster
  385.                    on 80386 machines.
  386.           
  387.                    If the source and destination blocks overlap, only
  388.                    forward moves (i.e. where the source base is greater ????
  389.                    than the destination base) are guaranteed to work
  390.                    properly.
  391.           
  392.                    Programs should not enable the A20 line before
  393.                    calling this function.  The state of the A20 line is
  394.                    preserved.
  395.  
  396.                    This function is guaranteed to provide a reasonable
  397.                    number of interrupt windows during long transfers.
  398.  
  399.                    The MoveStruc is a structure of type ExtMemMoveRec which
  400.                    is defined as follows :
  401.  
  402.                      ExtMemMoveRec = Record Case Boolean of
  403.                        False :
  404.                         (Length       : Longint; number of bytes to transfer
  405.                          SourceHandle : Word;    Handle of source block
  406.                          SourceOffset : Longint; offset into source
  407.                          DestHandle   : Word;    Handle of destination block
  408.                          DestOffset   : Longint; offset into dest block
  409.                         );
  410.                       True :
  411.                         (TheLenght    : Longint; lenght must be even !
  412.                          ZeroSource   : Word;    zero sourcehandle means a
  413.                          SourcePtr    : Pointer; ptr to "normal" memory
  414.                          ZeroDest     : Word;    zero dest handle means a
  415.                          DestPtr      : Pointer; ptr to "normal" memory
  416.                         );
  417.                      End; (* ExtMemMoveRec *)
  418.  
  419.      IN :          MoveStruc - Pointer to an Extended Memory Move
  420.                                Structure (see above).
  421.  
  422.      RETURNS :     XMMOk              - the move is successful.
  423.                    XMMNotImplemented  - the function is not implemented.
  424.                    XMMVDiskFound      - a VDISK device is detected.
  425.                    XMMA20Err          - an A20 error occurs.
  426.                    XMMSourceHanldeInv - the SourceHandle is invalid.
  427.                    XMMSourceOffsetInv - the SourceOffset is invalid.
  428.                    XMMDestHanleInv    - the DestHandle is invalid.
  429.                    XMMDestOffset      - the DestOffset is invalid.
  430.                    XMMLenInv          - the Length is invalid.
  431.                    XMMOverlap         - the move has an invalid overlap.
  432.                    XMMParity          - a parity error occurs.
  433.  
  434.      PRE :         XMMInstalled must have been called first.
  435.    ---------------------------------------------------------------------------}
  436.  
  437. Function XMMLockEMB (    Handle : Word;
  438.                      Var Linear : Longint) : Byte;
  439.   {---------------------------------------------------------------------------
  440.      ROUTINE :     XMMLockEMB
  441.  
  442.      DESCRIPTION : Locks an extended memory block and returns its base
  443.                    address as a 32-bit linear address.
  444.                    Locked memory blocks are guaranteed not to move.
  445.                    The 32-bit pointer is only valid while the block is
  446.                    locked because unlocked blocks may be moved by the
  447.                    XMS driver.
  448.                    Locked blocks should be unlocked as soon as possible.
  449.  
  450.                    NOTE: A block does not have to be locked before using
  451.                          XMMMoveEMB.
  452.           
  453.                    "Lock counts" are maintained for EMBs.
  454.  
  455.      IN :          Handle - Extended memory block handle to lock.
  456.  
  457.      OUT :         Linear - 32-bit linear address of the locked block.
  458.  
  459.      RETURNS :     XMMOk              - the block is locked.
  460.                    XMMNotImplemented  - the function is not implemented.
  461.                    XMMVDiskFound      - a VDISK device is detected.
  462.                    XMMInvalidHandle   - the handle is invalid.
  463.                    XMMLockOverflow    - the block's lock count overflows.
  464.                    XMMLockFail        - the lock fails.
  465.  
  466.      PRE :         XMMInstalled must have been called first.
  467.    ---------------------------------------------------------------------------}
  468.  
  469. Function XMMUnLockEMB (Handle : Word) : Byte;
  470.   {---------------------------------------------------------------------------
  471.      ROUTINE :     XMMUnLockEMB
  472.  
  473.      DESCRIPTION : Unlocks a locked extended memory block.  Any 32-bit
  474.                    pointers into the block become invalid and should no
  475.                    longer be used.
  476.  
  477.      IN :          Handle - Extended memory block handle to unlock.
  478.  
  479.      RETURNS :     XMMOk              - the block is unlocked.
  480.                    XMMNotImplemented  - the function is not implemented.
  481.                    XMMVDiskFound      - a VDISK device is detected.
  482.                    XMMInvalidHandle   - the handle is invalid.
  483.                    XMMEMBUnlocked     - the block is not locked.
  484.  
  485.      PRE :         XMMInstalled must have been called first.
  486.    ---------------------------------------------------------------------------}
  487.  
  488. Function XMMGetHandleInfo (    Handle      : Word;
  489.                            Var LockCount,
  490.                                FreeHandles : Byte;
  491.                            Var BlockLength : Word) : Byte;
  492.   {---------------------------------------------------------------------------
  493.      ROUTINE :     XMMGetHandleInfo
  494.  
  495.      DESCRIPTION : Returns additional information about an extended
  496.                    memory block to the caller.
  497.  
  498.                    NOTE: To get the block's base address, use XMMLockEMB.
  499.  
  500.      IN :          Handle      - Extended memory block handle.
  501.  
  502.      OUT :         LockCount   - The block's lock count.
  503.                    FreeHandles - Number of free EMB handles in the system.
  504.                    BlockLength - The block's length in K-bytes.
  505.  
  506.  
  507.      RETURNS :     XMMOk              - the block's information is found.
  508.                    XMMNotImplemented  - the function is not implemented.
  509.                    XMMVDiskFound      - a VDISK device is detected.
  510.                    XMMInvalidHandle   - the handle is invalid.
  511.  
  512.      PRE :         XMMInstalled must have been called first.
  513.    ---------------------------------------------------------------------------}
  514.           
  515. Function XMMReallocateEMB (Handle,
  516.                            NewSize : Word) : Byte;
  517.   {---------------------------------------------------------------------------
  518.      ROUTINE :     XMMReallocateEMB
  519.  
  520.      DESCRIPTION : Attempts to reallocate an unlocked extended memory
  521.                    block so that it becomes the newly specified size.
  522.                    If the new size is smaller than the old block's size,
  523.                    all data at the upper end of the old block is lost.
  524.  
  525.      IN :          Handle  - Unlocked extended memory block handle to
  526.                              reallocate.
  527.                    NewSize - New size for the extended memory block in
  528.                              K-bytes.
  529.  
  530.      RETURNS :     XMMOk              - the block is reallocated.
  531.                    XMMNotImplemented  - the function is not implemented.
  532.                    XMMVDiskFound      - a VDISK device is detected.
  533.                    XMMOutOfMemory     - all available extended memory is
  534.                                         allocated.
  535.                    XMMOutOfHandles    - all available extended memory
  536.                                         handles are in use.
  537.                    XMMInvalidHandle   - the handle is invalid.
  538.                    XMMEMBLocked       - the block is locked.
  539.  
  540.      PRE :         XMMInstalled must have been called first.
  541.    ---------------------------------------------------------------------------}
  542.  
  543. Function XMMRequestUMB (    RequestSize : Word;
  544.                         Var UMBSeg,
  545.                             BlockSize   : Word) : Byte;
  546.   {---------------------------------------------------------------------------
  547.      ROUTINE :     XMMRequestUMB
  548.  
  549.      DESCRIPTION : Attempts to allocate an upper memory block to the
  550.                    caller. If the function fails, the size of the
  551.                    largest free UMB is returned in DX.
  552.  
  553.                    NOTE: By definition UMBs are located below the 1MB
  554.                          address boundary.
  555.                          The A20 Line does not need to be enabled before
  556.                          accessing an allocated UMB.
  557.                          This function does not need to be implemented
  558.                          by an XMS driver.
  559.  
  560.                    UMBs are paragraph aligned.
  561.  
  562.                    To determine the size of the largest available UMB,
  563.                    attempt to allocate one with a size of FFFFh.
  564.  
  565.                    UMBs are unaffected by EMS calls.
  566.  
  567.      IN :          RequestSize - Size of requested memory block in
  568.                                  paragraphs (one paragraph is 16 bytes).
  569.  
  570.      OUT :         UMBSeg      - Segment number of the upper memory block.
  571.                    BlockSize   - If the request is granted, actual size
  572.                                  in paragraphs of the allocated block in
  573.                                  paragraphs.
  574.                                  Otherwise, size of the largest
  575.                                  available UMB in paragraphs.
  576.  
  577.      RETURNS :     XMMOk              - the request is granted.
  578.                    XMMNotImplemented  - the function is not implemented.
  579.                    XMMUMBSizeTooBig   - a smaller UMB is available.
  580.                    XMMNoUMBs          - no UMBs are available.
  581.  
  582.      PRE :         XMMInstalled must have been called first.
  583.    ---------------------------------------------------------------------------}
  584.   
  585. Function XMMReleaseUMB (UMBSeg : Word) : Byte;
  586.   {---------------------------------------------------------------------------
  587.      ROUTINE :     XMMReleaseUMB
  588.  
  589.      DESCRIPTION : This function frees a previously allocated upper
  590.                    memory block.
  591.                    When an UMB has been released, any code or data
  592.                    stored in it becomes invalid and should not be
  593.                    accessed.
  594.  
  595.                    NOTE: This function does not need to be implemented
  596.                          by an XMS driver.
  597.  
  598.      IN :          UMBSeg - Segment number of the upper memory block.
  599.  
  600.      RETURNS :     XMMOk              - the block was released.
  601.                    XMMNotImplemented  - the function is not implemented.
  602.                    XMMInvalidUMB      - the UMB segment number is invalid.
  603.  
  604.      PRE :         XMMInstalled must have been called first.
  605.    ---------------------------------------------------------------------------}
  606.     
  607. Function XMMReallocateUMB (RequestSize : Word;
  608.                            UMBSeg : Word) : Byte;
  609.  { ---------------------------------------------------------------------------
  610.      ROUTINE :     XMMReallocateUMB
  611.  
  612.      DESCRIPTION : This function attempts to reallocate an Upper Memory
  613.                    Block to a newly specified size. If the new size is
  614.                    smaller than the old block's size, all data at the
  615.                    upper end of the block is lost.
  616.  
  617.                    NOTE: This function does not need to be implemented
  618.                          by an XMS driver.
  619.  
  620.      IN :          UMBSeg - Segment number of the upper memory block.
  621.  
  622.      RETURNS :     XMMOk              - the block was released.
  623.                    XMMNotImplemented  - the function is not implemented.
  624.                    XMMUMBSizeTooBig   - a smaller UMB is available.
  625.                    XMMInvalidUMB      - the UMB segment number is invalid.
  626.  
  627.      PRE :         XMMInstalled must have been called first.
  628.    --------------------------------------------------------------------------- }
  629.  
  630. Function XMMQueryAnyFree (Var LargestFree,
  631.                               LastByte,
  632.                               TotalFree : LongInt): Byte;
  633.  
  634.  { ---------------------------------------------------------------------------
  635.      ROUTINE :     XMMQueryAnyFree
  636.  
  637.      DESCRIPTION : This function uses 32-bit values to return the size of
  638.                    available memory, thus allowing returns up to 4GByte.
  639.                    Additionally, it returns the highest known physical
  640.                    memory address, that is, the physical address of the
  641.                    last byte of memory.  There may be discontinuities in
  642.                    the memory map below this address.
  643.  
  644.                    The memory pool reported on is the same as that
  645.                    reported on by the existing Query Free Extended Memory
  646.                    function 08h.  If the highest memory address is not
  647.                    more than 64 Mb, then these two functions will return
  648.                    the same results.
  649.  
  650.                    Because of its reliance on 32-bit registers, this
  651.                    function is only available on 80386 and higher
  652.                    processors.  XMS drivers on 80286 machines should
  653.                    return error code 80h if this function is called.
  654.  
  655.                    If error code 81h is returned, the value in ECX will
  656.                    still be valid.  If error code A0h is returned, EAX and
  657.                    EDX will be 0, and ECX will still be valid.
  658.  
  659.      OUT :         LargestFree - Size of the largest free extended
  660.                                  memory block in K-bytes.
  661.                    LastByte    - Physical address of the last byte in memory.
  662.                    TotalFree   - Total amount of free extended memory in
  663.                                  K-bytes.
  664.  
  665.      RETURNS :     XMMOk              - the function succeeds.
  666.                    XMMNotImplemented  - the function is not implemented.
  667.                    XMMVDiskFound      - a VDISK device is detected.
  668.                    XMMOutOfMemory     - all available extended memory is
  669.                                         allocated.
  670.  
  671.      PRE :         XMMInstalled must have been called first.
  672.    --------------------------------------------------------------------------- }
  673.  
  674. Function XMMAllocateAnyEMB (    BlockSize : Longint;
  675.                             Var Handle    : Word) : Byte;
  676.  { ---------------------------------------------------------------------------
  677.      ROUTINE :     XMMAllocateAnyEMB
  678.  
  679.      DESCRIPTION : This function is similar to the existing Allocate
  680.                    Extended Memory 09h, except that it uses a 32-bit
  681.                    instead of a 16-bit value to specify the amount of
  682.                    memory requested.  It allocates from the same memory
  683.                    and handle pool as the current function.
  684.  
  685.                    Since it requires a 32-bit register, this function can
  686.                    be supported only on 80386 and higher processors, and
  687.                    XMS drivers on 80286 machines should return error code
  688.                    80h.
  689.  
  690.      IN :          BlockSize - Amount of extended memory being requested
  691.                                in K-bytes.
  692.  
  693.      OUT :         Handle    - 16-bit handle to the allocated block.
  694.  
  695.      RETURNS :     XMMOk              - the block is allocated.
  696.                    XMMNotImplemented  - the function is not implemented.
  697.                    XMMVDiskFound      - a VDISK device is detected.
  698.                    XMMOutOfMemory     - all available extended memory is
  699.                                         allocated.
  700.                    XMMOutOfHandles    - all available extended memory
  701.                                         handles are in use.
  702.  
  703.      PRE :         XMMInstalled must have been called first.
  704.    --------------------------------------------------------------------------- }
  705.  
  706. Function XMMGetExtendedHandleInfo (    Handle      : Word;
  707.                                    Var LockCount   : Byte;
  708.                                    Var FreeHandles : Word;
  709.                                    Var BlockLength : Longint) : Byte;
  710.  
  711.  { ---------------------------------------------------------------------------
  712.      ROUTINE :     XMMGetExtendedHandleInfo
  713.  
  714.      DESCRIPTION : This function is similar to the Get EMB Handle
  715.                    Information function. Since it uses a 32-bit register
  716.                    to report the block size, it can be used to get
  717.                    information on blocks larger than 64 Mb.  It also uses
  718.                    a 16-bit instead of 8-bit register to report the number
  719.                    of free handles, allowing the handle pool to be
  720.                    extended beyond 256 entries.
  721.  
  722.                    Because of its reliance on a 32-bit register, this
  723.                    function is available on 80386 and higher processors.
  724.                    XMS drivers on 80286 machines should return error code
  725.                    80h if this function is called.
  726.  
  727.      IN :          Handle      - Extended memory block handle.
  728.  
  729.      OUT :         LockCount   - The block's lock count.
  730.                    FreeHandles - Number of free EMB handles in the system.
  731.                    BlockLength - The block's length in K-bytes.
  732.  
  733.  
  734.      RETURNS :     XMMOk              - the block's information is found.
  735.                    XMMNotImplemented  - the function is not implemented.
  736.                    XMMVDiskFound      - a VDISK device is detected.
  737.                    XMMInvalidHandle   - the handle is invalid.
  738.  
  739.      PRE :         XMMInstalled must have been called first.
  740.    --------------------------------------------------------------------------- }
  741.  
  742. Function XMMReallocateAnyEMB (Handle,
  743.                               NewSize : Longint) : Byte;
  744.  
  745.  { ---------------------------------------------------------------------------
  746.      ROUTINE :     XMMReallocateAnyEMB
  747.  
  748.      DESCRIPTION : This function is similar to the existing Reallocate
  749.                    Extended Memory, except that it uses a 32-bit instead
  750.                    of a 16-bit value to specify the amount of memory
  751.                    requested.  It allocates from the same memory and
  752.                    handle pool as the current function.
  753.  
  754.                    Since it requires a 32-bit register, this function can
  755.                    be supported only on 80386 and higher processors, and
  756.                    XMS drivers on 80286 machines should return error code
  757.                    80h.
  758.  
  759.      IN :          Handle  - Unlocked extended memory block handle to
  760.                              reallocate.
  761.                    NewSize - New size for the extended memory block in
  762.                              K-bytes.
  763.  
  764.      RETURNS :     XMMOk              - the block is reallocated.
  765.                    XMMNotImplemented  - the function is not implemented.
  766.                    XMMVDiskFound      - a VDISK device is detected.
  767.                    XMMOutOfMemory     - all available extended memory is
  768.                                         allocated.
  769.                    XMMOutOfHandles    - all available extended memory
  770.                                         handles are in use.
  771.                    XMMInvalidHandle   - the handle is invalid.
  772.                    XMMEMBLocked       - the block is locked.
  773.  
  774.      PRE :         XMMInstalled must have been called first.
  775.    --------------------------------------------------------------------------- }
  776.  
  777.  
  778.  
  779.  
  780. {-----------------------------------------------------------------------------}
  781. {                                                                             }
  782. {                      Implementation                                         }
  783. {                                                                             }
  784. {-----------------------------------------------------------------------------}
  785.  
  786. Implementation
  787.  
  788.  
  789. {$L XMM.OBJ }  { Link in the assembler part }
  790.  
  791.  
  792.  
  793. Function XMMInstalled;                  External;
  794.  
  795. Function XMMVersion;                    External;
  796.  
  797. Function XMMRequestHMA;                 External;
  798. Function XMMReleaseHMA;                 External;
  799.  
  800. Function XMMGlobalEnableA20;            External;
  801. Function XMMGlobalDisableA20;           External;
  802. Function XMMLocalEnableA20;             External;
  803. Function XMMLocalDisableA20;            External;
  804. Function XMMQueryA20;                   External;
  805.  
  806. Function XMMQueryFree;                  External;
  807.  
  808. Function XMMAllocateEMB;                External;
  809. Function XMMFreeEMB;                    External;
  810.  
  811. Function XMMMoveEMB;                    External;
  812.  
  813. Function XMMLockEMB;                    External;
  814. Function XMMUnLockEMB;                  External;
  815.  
  816. Function XMMGetHandleInfo;              External;
  817.  
  818. Function XMMReallocateEMB;              External;
  819.  
  820. Function XMMRequestUMB;                 External;
  821. Function XMMReleaseUMB;                 External;
  822. Function XMMReallocateUMB;              External;
  823.  
  824. Function XMMQueryAnyFree;               External;
  825.  
  826. Function XMMAllocateAnyEMB;             External;
  827.  
  828. Function XMMGetExtendedHandleInfo;      External;
  829.  
  830. Function XMMReallocateAnyEMB;           External;
  831.  
  832. End.
  833.  
  834.  
  835. ----------------------------------------------------------------------------
  836.  
  837.    Some notes about HMA usage from the official Microsoft documentation.
  838.  
  839. ----------------------------------------------------------------------------
  840.  
  841.  
  842. PRIORITIZING HMA USAGE:
  843. -----------------------
  844.  
  845.     For DOS users to receive the maximum benefit from the High Memory Area,
  846. programs which use the HMA must store as much of their resident code in it as
  847. is possible.  It is very important that developers realize that the HMA is
  848. allocated as a single unit. 
  849.  
  850.     For example, a TSR program which grabs the HMA and puts 10K of code into
  851. it may prevent a later TSR from putting 62K into the HMA.  Obviously, regular
  852. DOS programs would have more memory available to them below the 640K line if
  853. the 62K TSR was moved into the HMA instead of the 10K one.
  854.  
  855.     The first method for dealing with conflicts such as this is to require 
  856. programs which use the HMA to provide a command line option for disabling
  857. this feature.  It is crucial that TSRs which do not make full use of the HMA
  858. provide such a switch on their own command line (suggested name "/NOHMA").
  859.  
  860.     The second method for optimizing HMA usage is through the /HMAMIN=
  861. parameter on the XMS device driver line.  The number after the parameter
  862. is defined to be the minimum amount of HMA space (in K-bytes) used by any
  863. driver or TSR.    For example, if "DEVICE=HIMEM.SYS /HMAMIN=48" is in a
  864. user's CONFIG.SYS file, only programs which request at least 48K would be
  865. allowed to allocate the HMA.  This number can be adjusted either by
  866. installation programs or by the user himself.  If this parameter is not
  867. specified, the default value of 0 is used causing the HMA to be allocated
  868. on a first come, first served basis.
  869.  
  870.     Note that this problem does not impact application programs.  If the HMA
  871. is available when an application program starts, the application is free to
  872. use as much or as little of the HMA as it wants.  For this reason,
  873. applications should pass FFFFh in DX when calling Function 01h.
  874.  
  875. HIGH MEMORY AREA RESTRICTIONS:
  876. ------------------------------
  877.  
  878. -   Far pointers to data located in the HMA cannot be passed to DOS.  DOS
  879.     normalizes any pointer which is passed into it.  This will cause data
  880.     addresses in the HMA to be invalidated.
  881.  
  882. -   Disk I/O directly into the HMA (via DOS, INT 13h, or otherwise) is not
  883.     recommended.
  884.        
  885. -   Programs, especially drivers and TSRs, which use the HMA *MUST* use
  886.     as much of it as possible.  If a driver or TSR is unable to use at
  887.     least 90% of the available HMA (typically ~58K), they must provide
  888.     a command line switch for overriding HMA usage.  This will allow
  889.     the user to configure his machine for optimum use of the HMA.
  890.        
  891. -   Device drivers and TSRs cannot leave the A20 line permanently turned
  892.     on.  Several applications rely on 1MB memory wrap and will overwrite the
  893.     HMA if the A20 line is left enabled potentially causing a system crash.
  894.         
  895. -   Interrupt vectors must not point into the HMA.  This is a result of
  896.     the previous restriction.  Note that interrupt vectors can point into
  897.     any allocated upper memory blocks however.
  898.  
  899.  
  900. The description of all functions and the notes about HMA usage are
  901.  
  902.  
  903.  
  904.               Copyright (c) 1988-1992 Microsoft Corporation.
  905.  
  906.  
  907.  
  908.  
  909. Because this XMM is public domain (as is HIMEM) I am so free to use
  910. that text and I won't accept any claims from anyone for it.
  911. Furthermore I also use the same disclaimer as in XMS.TXT on the HIMEM
  912. distribution disk :
  913.  
  914. Disclaimer of Warranty:
  915. -----------------------
  916.  
  917. I, JEROEN W. PLUIMERS, FURTHER CALLED "THE AUTHOR" AND MY COMPANY
  918. EXCLUDE ANY AND ALL IMPLIED WARRANTIES, INCLUDING WARRANTIES OF
  919. MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. NEITHER THE AUTHOR
  920. NOR HIS COMPANY MAKE ANY WARRANTY OF REPRESENTATION, EITHER EXPRESS OR
  921. IMPLIED, WITH RESPECT TO THIS EXTENDED MEMORY MANAGER, ITS QUALITY,
  922. PERFORMANCE, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.
  923. NEITHER THE AUTHOR NOR HIS COMPANY SHALL HAVE ANY LIABILITY FOR SPECIAL,
  924. INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF OR RESULTING FROM
  925. THE USE OR MODIFICATION OF THIS EXTENDED MEMORY MANAGER.
  926.  
  927.